<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>StringConversion</title>
  <link rel="stylesheet" type="text/css" href="DoX.css"/>
</head>
<body>
  <div class="DoX">
<h1>String conversion</h1>

<p>Two procedures are provided to simplify reading data retreved from XML documents into Fortran variables. The subroutine <code>rts</code> performs the data conversion step and the function <code>countrts</code> can be used to allocate an array of the correct size for the incomming data. </p>

<h2><code>rts</code> subroutine</h2>

<p>The <code>rts</code> subroutine can be imported from <code>FoX_common</code>. In its simplest form, it is called in this fashion:</p>

<pre><code>call rts(string, data)
</code></pre>

<p><code>string</code> is a simple Fortran string (probably retrieved from an XML file.)</p>

<p><code>data</code> is any native Fortran datatype: <code>logical</code>, <code>character</code>, <code>integer</code>, <code>real</code>, <code>double precision</code>, <code>complex</code>, <code>double complex</code>, and may be a scalar, 1D or 2D array.</p>

<p><code>rts</code> will attempt to parse the contents of <code>string</code> into the appropriate datatype, and return the value in <code>data</code>.</p>

<p>Additional information or error handling is accomplished with the following optional arguments:</p>

<h3><code>num</code></h3>

<p><code>num</code> is an integer; on returning from the function it indicates the number of data items read before either:</p>

<ul>
<li>an error occurred</li>
<li>the string was exhausted of data items  </li>
<li><code>data</code> was filled.</li>
</ul>

<h3><code>iostat</code></h3>

<p><code>iostat</code> is an integer, which on return from the function has the values:</p>

<ul>
<li><code>0</code> for no problems</li>
<li><code>-1</code> if too few elements were found in <code>string</code> to fill up <code>data</code></li>
<li><code>1</code> if <code>data</code> was filled, but there were still data items left in <code>string</code></li>
<li><code>2</code> if the characters found in <code>string</code> could not be converted to the appropriate type for <code>data</code>.</li>
</ul>

<p>NB if <code>iostat</code> is not specified, and a non-zero value is returned, then the program will stop with an error message.</p>

<h2>String formatting</h2>

<p>When <code>string</code> is expected to be an array of strings, the following options are used to break <code>string</code> into its constituent elements:</p>

<ul>
<li><p>By default it is assumed that the elements are separated by whitespace, and that multiple whitespace characters are not significant. No zero-length elements are possible, nor are elements containing whitespace.</p></li>
<li><p>An optional argument, <code>separator</code> may be specified, which is a single character. In this case, each element consists of all characters between subsequent occurences of the <code>separator</code>. Zero-length elements are possible, but no escaping mechanism is possible.</p></li>
<li><p>Alternatively, an optional logical argument <code>csv</code> may be specified. In this case, the value of <code>delimiter</code> is ignored, and the string is parsed as a Comma-Separated-Value string, according to <a href="http://tools.ietf.org/html/rfc4180">RFC 4180</a>.</p></li>
</ul>

<h2>Numerical formatting.</h2>

<p>Numbers are expected to be formatted according to the usual conventions for Fortran input.</p>

<h2>Complex number formatting.</h2>

<p>Complex numbers may be formatted according to either normal Fortran conventions (comma-separated pairs) or <a href="http://cmlcomp.org/t/wiki/FpxStandard">CMLComp conventions</a></p>

<h2>Logical variable formatting.</h2>

<p>Logical variables must be encoded according to the conventions of <a href="http://www.w3.org/TR/xmlschema-2/#boolean">XML Schema Datatypes</a>  - that is, True may be written as "true" or "1", and False may be written as "false" or "0".</p>

<h2><code>countrts</code> function</h2>

<p>The <code>countrts</code> function can also be imported from <code>FoX_common</code>. In its simplest form, it is called in this fashion:</p>

<pre><code>countrts(string, datatype)
</code></pre>

<p><code>string</code> is a simple Fortran string (probably retrived from an XML file)</p>

<p><code>datatype</code> is a scalar argument of any native Fortran datatype (<code>logical</code>, <code>character</code>, <code>integer</code>, <code>real</code>, <code>double precision</code>, <code>complex</code> or <code>double complex</code>).</p>

<p>The function returns a default integer equal to the number of elements that rts would
return if called with a sufficently large array of the same type as <code>datatype</code>. <code>countrts</code> returns 0 to indicate that characters were found in the string that could not be converted. If datatype is a character, the optional arguments <code>seperator</code> and <code>csv</code> are avalable as described in "string formatting" above. The <code>countrts</code> function is pure and can be used as a specification function.</p>
</div>
</body>
</html>
